
					Abstract

This is a help file for the Mac Menu in Alpha.
This file should be located in the Help subfolder of Alpha's folder to
show up automatically in the Help menu when Alpha is loaded. It documents 
version 2.3 of the package.



----------------------------------------------------------------------
   1. Introduction
   2. Installation
      2.1. Automatic installation
      2.2. Manual installation
      2.3. After installing
   3. Quick start
   4. Dialogs description
      4.1. Main selection dialogs
      4.2. Renaming dialog
      4.3. Particular dialogs
      4.4. Information dialog windows
   5. Menu Items Description
      5.1. Main menu
      5.2. Get Info submenu
   6. Mac Shell Syntax
      6.1. Shell prompt
      6.2. 'help' command
      6.3. 'files' command
         6.3.1. Options for the files command
         6.3.2. Subcommands of the 'files' command
      6.4. 'infos' command
      6.5. Commands for browsing
      6.6. Other commands
      6.7. Unix commands
      6.8. Commands history
      6.9. Extending Mac Shell
   7. MacMenu programming interface
   8. Completion mechanism
   9. Getting info
   10. Key Bindings
   11. Preferences
   12. Version History
   13. Known problems
   14. License and Disclaimer
----------------------------------------------------------------------

1. Introduction

Mac Menu for Alpha allows you to achieve all kinds of  files  manipulations
from Alpha and  to  interact  with  the  MacOS  file  system  with  maximum
flexibility.

You can act upon selections of files taken out of a folder or  a  hierarchy
of folders  and  subfolders:  the  selection  is  made  using  a  regular
expression (regexp) and setting various  additional  conditions.  You  have
thus full and extended control on which files you want to manipulate.

Actions executed on the selected files are:  copying,  moving,  renaming,
duplicating, trashing/untrashing, locking  or  unlocking,  making  aliases,
selecting or unselecting, listing, changing creator type.

You can also get complete system information about all  kinds  of  elements
such as files, folders, disks,  processes  etc.  and  set  new  values  for
certain properties (change a type, a creator, a modification date,  sharing
status etc.). Commands  are  also  provided  for  basic  Finder's  tasks:
emptying the trash, restarting the computer etc.

All the commands are available from a menu called Mac Menu but the  package
also implements a 'shell' to execute all these  functions  from  a  command
line. For instance, just type 'empty' at the prompt of Mac Shell  to  empty
the trash. A very simple syntax  is  provided  to  write  commands  and  to
navigate in the MacOS files system.

All these actions are executed  without  leaving  the  Alpha  editor.  The
package is almost exclusively based on Apple Events sent to the system.

See the tutorial file and  read  more  information  below  for  a  complete
description of all the items available in Mac Menu.

Starting from version 2.3, Mac Menu runs only with AlphaX on OSX. To run it
under OS8 or OS9 you must get an older version of the package.


2. Installation

2.1. Automatic installation

If you received Mac Menu with a regular distribution of Alpha, there's
nothing particular to do: it is already installed and you just have to turn
it on (see After installing below). Otherwise, the simplest way of
installing the package is to use the automatic installation facility. Just
double-click on the OPEN TO INSTALL file. Opening this file tells Alpha
that a new package has to be installed: the procedure is automatic. Alpha
knows where to store the different elements of your 'Mac Menu' package.

2.2. Manual installation

If you prefer a manual installation, take the following steps:
    1. put the macMenu folder in the Menus subfolder of the
Tcl folder which is located at the same level as your Alpha
application

    2. put the Mac Menu Help files in the Help folder located at the same
level as your Alpha application. Next time you launch Alpha, you will see a
Mac Menu Help item in the Help menu.

    3. put the MacMenu-Example and MacMenu-Example.tcl files in thefolder
called Mode  Examples  and  located  at  the  same  level  as  the  Alpha
application.

    4. launch Alpha. You have to  rebuild  the  package  indices  and  the  Tcl
indices. Rebuild Package Indices is in  the  Config / Packages  menu,  and
Rebuild Tcl Indices is in the Tcl menu.

    5. quit Alpha and relaunch it: that's all there is to it.


2.3. After installing

Have a look at the Mac Menu preferences in the Packages  submenu  of  the
Config menu. You can set various flags there. More explanations below.

Image: ../Images/macmenu.gif

3. Quick start

Suppose you have a folder containing all the pages of a Web  site  and  you
want a list of the image files having extension gif or jpeg. 
In the List Files dialog window, specify the folder and click on the
Extensions button. In the new window check gif and jpeg and press OK.
This brings back to the previous window in which the Files Filter is now
set like this:

    .*\.(jpeg|gif)

Click OK and you get the list you wanted. You could have specified 
In all Subfolders in the Process popup menu to get a list including
files in the nested subfolders.

Suppose now you want to send to another folder a copy of  the  files  taken
out of this structure whose names meet the following requirements:
     first letter is A or P
     the extension is htm or html
     the name contains a suffix _XY
     the files were modified after Dec 25, 2000
     their size is less than 128k (to exclude big images for instance)

You have to  build  a  regular  expression  representing  the  first  three
conditions. In the Copy Files dialog window, the Files Filter should be:

    [AP].*_XY\.html?

Then click on the Add conditions button and in the new  window,  set  the
last two contitions like so:

    Modification date after 2000-12-25
    Size greater than 128k

leaving the other fields blank.
Clicking on Apply brings back to the previous dialog in which you set the
paths of the source and the target folders. In the  Process  popup  menu,
choose in all Subfolders. Now click on Copy and there you go. The  copy
sent to the target folder will reproduce  exactly  the  same  hierarchy  of
folders and subfolders but will contain only the files corresponding to the
required scheme.

Now suppose you want to rename the selected files. You want the new name to
be like this:
     first letter Q instead of A or P
     following letters unchanged
     no _XY suffix
     extension old
     all file names in uppercase letters

Unless you cancelled in the Copy Files dialog window, all  your  settings
will have been preserved when you open the Rename Files window. You  have
just one modification to do in the Files Filter regular expression: add  a
pair of parentheses to capture the .* part which will be refered to  as  \1
in the substitution expression:

    [AP](.*)_XY\.html?

The replacement string will then be:

    Q\1\.old

To have uppercase letters, click on the Add options button.  In  the  new
window, click on the Casing checkbox and choose UPPERCASE  in  the  popup
menu. Click Apply then click Rename. That's all there is to it.


4. Dialogs description

Almost all the  dialog  windows  in  which  you  specify  the  options  and
conditions related to some kind of file manipulation share common elements.


4.1. Main selection dialogs

The top part of the dialog is an edit field in which you  write  a  regular
expression describing the naming scheme of the files you want to act  upon.
It is very important to note that it obeys the regular  expressions  syntax
and not the so-called 'globbing syntax' used in some Tcl commands. For more
info about the regular expressions, read the Regular Expressions file  in
the Help Menu. Regular expressions are a very powerful syntax  designed  to
describe abstractly almost any kind of strings.

The top part of the dialog windows also contains  two  check  boxes  called
case sensitive and negate filter: check or uncheck them as  you  want.
If the negate filter checkbox is checked, Mac Menu will search for  files
which do NOT correspond to the files  filter  regular  expression.  If  the
case sensitive checkbox is unchecked, Mac Menu will not take casing  into
account: uppercase and lowercase letters will be considered equivalent.
The Add Conditions button calls a new dialog  window  in  which  you  can
specify additional options concerning the MacOS  type  or  creator  of  the
files, the date of creation or modification and the size (in kbytes). Dates
are indicated in the ISO format (yyyy-mm-dd).

NB: the negate  filter  flag,  if  set,  negates  the  filtering  regular
expression but NOT the additional conditions. They are... additional.

A pop-up menu lets you specifiy whether an action should be  taken  on  all
the files corresponding to the filter in the current directory,  or  should
be extended to the subfolders down to a specified level as well or even  to
all subfolders, subsubfolders etc.

Almost all the dialog windows contain an edit field to specify  the  source
folder: the folder in which to look for files or the folder at the top  of
the hierarchy if subfolders are concerned too. You can write  the  complete
path of the source folder in the edit field or  use  the  Set  button  to
browse through the file system with a standard dialog.

When relevant (to copy or move files), an additional edit  field  lets  you
choose a target folder.  If  files  are  taken  out  of  a  hierarchy,  the
hierarchy will be transported to  the  target  folder:  if  corresponding
subfolders do not  exist  in  the  target  folder,  they  will  be  created
automatically. If the target folder itself does not exist,  it  is  created
too so you can specify the name of a non existing folder in the edit field.
Use the Set button to choose an existing folder.

All the dialog windows have at least two buttons  at  the  bottom:  one  to
execute the desired action, one to cancel.


4.2. Renaming dialog

The Rename Files dialog window contains  a  specific  field  to  set  the
renaming scheme: it uses the substitution syntax of  regular  expressions.
So you can use the special substitution symbols: & to designate the entire
match, \1, \2 etc. to designate sub-expressions corresponding to  pairs  of
parentheses in the files filtering regular expression.
A button called Add Options brings up a new dialog window  in  which  you
can choose more options. They concern  casing,  incremental  numbering  and
truncating. Tey have the following meaning:
     the casing option is  self  explanatory:  change  to  UPPERCASE  or
lowercase, Capitalize Words or Capitalize first letter only.

     the numbering facility has various settings: numbering  from  zero  or
from one, appending the number at the beginning or at the  end  of  the  new
file name, number in increasing or decreasing order. The padd  with  zeros
option corresponds to the insertion of zeros at the left of the number  when
necessary: such as in 01, 02 etc. or 001, 002 etc.

     the truncating facility lets you specify a format for the new file 
names.
The default value  is  8.3  which  corresponds  to  the  MS-DOS  limitation
concerning file names: eight letters at most, a dot, three letters at  most
after the dot. The general syntax is m[.n] which means a single integer  or
two integers separated by a dot as in the 8.3 example. In  the  first  case
all file names will be truncated to a maximum of m  characters  whereas  in
the second case, if a file name has an extension, the part before  the  dot
will be truncated to a maximum of m characters and the part after  the  dot
to a maximum of n characters.


4.3. Particular dialogs

The Trash Files dialog has no target folder field:  the  target  is  the
trash. The Untrash Files dialog is different from the others and proposes
two options: last trashed or all. In the first case, will be untrashed
(i-e sent back to their original position in the  files  system)  only  the
files most recently trashed from the Trash Files item in  the  Mac  Menu.
This is a sort of 'undo' facility if you have accidentally trashed files or
have a remorse. With the all option, all the files currently in the trash
will be untrashed.


The Change Creator dialog has an additional button called Other: if  a
creator type is not in the popup menu, you can specify  another  one.  This
button brings up a new dialog with an edit field to enter the  new  creator
type (four chars maximum). If you do  not    know    the    creator    type
corresponding to an application, use the Same as button and indicate  the
application or any document created  with  this  application.  The  Apply
button selects the new type and brings back the Change Creator  dialog  ;
the Add&Apply button has the same effect but additionally records the new
type in the popup menu to make it available for future  use  (the  list  is
reset though each time Alpha is relaunched: to make an addition  permanent
use the Mac Menu Preferences. See section below about preferences).


The Extensions button is a facility  to  specify  files  with  particular
extensions. It brings up a new dialog with several checkboxes:  select  the
extensions you're interested in by checking the corresponding checkbox. The
corresponding files filter regular expression will be  built  automatically
in the main dialog  window.  If  an  extension  is  not  mentioned  in  the
Predefined Extensions dialog window, you have two possibilities:
     for a temporary usage, enter it in the Other extensions edit  field.
A list of space-separated extensions can be entered there.  You  can  enter
the extensions with or without the dot, this makes no difference.

     for a permanent usage, you  might  want  to  add  your  favorite  file
extensions to the Mac Menu Preferences (see the section  about  preferences
below). In this case, the new extensions will have a checkbox of their own.
 


4.4. Information dialog windows


The information windows display information about  all  kinds  of  items:
files, folders, volumes, applications, processes or  basic  hardware.  They
almost all have a Dismiss, a Get Text. The File Infos dialog also has a
Set button. With the Dismiss button, you simply quit  the  dialog.  The
Get Text button sends  the  collected  information  to  a  separate  text
window.
The Set button allows you to set  some  properties:  the  corresponding
fields are editable (an edit field for a  variable  or  a  checkbox  for  a
flag). You validate your modifications with the Set button. Note that  if
your file is locked the modifications are not appliable:  you  must  first
unlock it. Be aware of what you are doing: changing low  level  properties
is potentially dangerous. Don't play with the system files.
In the case of a shared volume or folder, and if file sharing is on on  the
system, there is an additional Sharing button which gets and displays the
complete sharing information about the item.


5. Menu Items Description

Here is the list of all the menu items of the Mac Menu  with  explanations.
Certain items are obtained if you hold the Option Key  down  while  opening
the menu.

5.1. Main menu

<Copy Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the  source  and  target  folders  and  various
options. Copy the selected files to the target creating
the same  hierarchy  in  the  destination  folder.  The
original files remain in the source folder.

<Move Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the  source  and  target  folders  and  various
options. Move the selected files to the target creating
the same  hierarchy  in  the  destination  folder.  The
original files are removed from the source folder.
Note that, as is the rule with MacOS, moving a file  to
another volume means in fact copying.

<Rename Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the replacement expression, the  source  folder
and various renaming options: the Add Options button
brings a  new  dialog  to  set  casing,  numbering  and
truncating options. Rename the selected files according
to the new scheme.

<Duplicate Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder    and    various    options.
Duplicate the selected files in their original folder.

<Trash Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and  various  options.  Sends
the selected files to the trash:  the  files  are  not
deleted until you empty the trash.

<Alias Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and various options. You  can
also optionnally specify a target folder. There are two
possibilities:

     if no target folder is specified (empty field) or  if
it is the same as the source folder, then  the  aliases
are made in the same folders (and  subfolders  if  they
are in a hierarchy) as the original files
     if a target folder is specified then all the  aliases
are sent to this folder no matter  where  the  original
files are located in the source folder, i-e even if the
'In hierarchy' flag is used. If this target folder does
not exist, it is created.


When holding the option key down:

<Remove Alias Files>

Brings up a dialog in  which  you  specify  the  source
folder and the subfolders  level.  Remove  all  aliases
found in these folders.


<Lock Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and various options. Lock the
selected files in their original folder.


When holding the option key down:

<Unlock Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and various  options.  Unlock
the selected files if they are locked.


<List Files>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and various  options.  Simply
makes a list of the files  selected  according  to  the
files filter and the various options and display it  in
a separate window.
The Sort by pop-up menu allows you to choose  one  of
five options (or no option) so that the  list  returned
is sorted according to the selected criterion. You  can
sort by: Modification date, Creation date, Size,
Kind, Labels. Check the  Include  Criterion  checkbox  to
include the value of the criterion for each item in the
result.

<Change Encoding>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder, the current encoding of  the
files, and a target encoding in order to  convert  them
to this encoding.

<Change Eols>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and the environment the files
belong to in order to convert the line endings  between
the various plateform specific  types  (mac,  unix  and
win). For instance if you choose to convert  eols  (end
of lines) from unix to mac, only Unix type  files  will
be converted to the Mac  type.  If  you  choose  all,
conversion applies to all three kinds of files.

<Change Creator>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and various options: a popup
list lets you choose the new creator you want to assign
to the selected files. Use the  Other  button  to  find
another creator.

<Change Type>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder and various options: a popup
list lets you choose the new type you want to assign to
the selected  files.  Use  the  Other  button  to  find
another type.

<Delete Rez Forks>

Brings up a dialog  in  which  you  specify  the  files
filter, the source folder  and  various  options.  This
will delete the resource fork of the  files.  You  will
use this typically if you want to transmit  some  files
to another environment (Unix, Windows) in  which  there
is no notion of a resource fork.

<Mac Shell>

Opens a shell in which all the Mac Menu  functions  can
be executed from a command  line.  See  below  the  Mac
Shell section for details on the syntax of this command
line.

<Empty Trash>

Empty the trash.

<Eject>

Eject a removable volume (floppy, Zip, CD-ROM etc.). If
there are several ejectable volumes, a  list  shows  up
from which you select the one you want  to  eject  from
its drive ; if there is only one ejectable  volume,  it
is automatically ejected.

<Sleep>

Puts the computer to sleep.

<Restart>

Launches the process of restarting the computer.

<Shut Down>

Launches the process of shuting down the computer.



5.2. Get Info submenu
Image: ../Images/macmenugetinfo.gif



<File / Folder / Application>

With these three items, a standard system  window  lets
you designate the file,  folder  or  application  about
which you want to get system information.

<Volume / Process>

With these two items, a list  of  all  mounted  volumes
(and shared disks on remote computers)  or  a  list  of
currently running processes lets you choose the one you
want information about.

<Hardware>

(not available on OSX) 
Provides general hardware  information    about    your
computer (clock speed, CPU, etc.)

<Mac Menu Bindings>
Shows all the key bindings available with the Mac  Menu
in a separate window. See the  Key  Bindings  section
below.

<Mac Menu Tutorial>
Opens the tutorial file.



6. Mac Shell Syntax

The Mac shell provides a command line facility analogous to the  Tcl  shell
('cmd-y') or the now obsolete Toolsever shell already available in Alpha.
You can open it with the Mac Shell menu item or with the 'ctrl-cmd-y'  key
combination. This section lists all  the  commands  available  in  the  Mac
Shell.
 The main commands are 'help',  'files'  and  'infos'.  There  are  also
commands which allow you to navigate in the MacOS  files  system:  'pwd',
'cd', 'ls', 'ld'. Additionally you have a few utility commands:  'empty',
'eject', 'restart', 'shutdown' which behave  like  the  corresponding  menu
items. 
Please see the tutorial (choose Mac  Menu  Tutorial  in  the  Get  Info
submenu) for real life examples.
 Certain options are not handled from the command line though:  if  you
want to specify additional  conditions  (as  explained  above)  you  should
rather use the dialog windows.
 If a command is not a specific Mac Shell command, MacMenu  will  try  to
evaluate it as a Tcl instruction. If no Tcl command is found, then  it  will
try to execute it as a Unix command (only on OSX). This means that  you  can
use Mac Shell as a Tcl shell and that you can execute Unix command  directly
from Alpha (see more precisions in the Unix commands section below).


6.1. Shell prompt
The shell prompt always indicates the  name  of  the  current  folder.  When
opening the shell, its value defaults to the Alpha application's main folder
or to the currently logged in user's home directory (see the Default  Home
preference). 


6.2. 'help' command

The 'help' command  can  be  used  alone  or  with  one  of  the  following
arguments:
 help           to have a list of all available commands          
 help -options  to have a list of all available options and flags 
 help [cmdname] to display info about a specific command          



6.3. 'files' command

The 'files' command is used with a subcommand to specify the type of action
which is to be executed and flags to specify the conditions and options.

6.3.1. Options for the files command

Here is the  signification  of  the  various  options.  Some  of  them  are
required, the others  have  default  values  and  can  be  omitted  if  not
necessary. 

 -f filter      filtering regular expr            default '.*'           
 -s folder      source folder                     default current folder 
 -l level       nesting level (0, 1,... or all)   default 0              
 -i flag        case sensitive?                   default 0              
 -n flag        negate?                           default 0              
 -t folder      target folder                     no default             
 -t enc         target encoding in transcode      default iso8859-1      
 -t kind        target eol in transtype           default mac            
 -t type        file's type                       no default             
 -c type        file's creator                    no default             
 -o flag        force overwrite?                  default: see prefs     
 -o enc         original encoding in transcode    default macRoman       
 -o kind        original eol in transtype         default unix           
 -r replace     regsub expr for renaming          default &              
 -all           all files (equivalent to '-f .*') no value               
 -k flag        casing: u, l, w, f                default: not set       
 -d flag        numbering: 0/1                    default: not set       
 -b (m|c|s|k|l) sort by                           no default             
 -x m[.n]       truncate                          default: not set       


Note that the -c option is interpreted differently with the files  change
command than with the other files command: in the first case, it is  the
required option which tells which new creator should  be  assigned  to  the
selected files. In the second case, it is an optional argument telling that
only the files with the type declared by -c should be selected  to  perform
the action.
 Similarly the -t option is  interpreted  differently  with  the  
files change command than with the other files command: 
     used with files change, it is the required option which tells
which new type should be assigned to the selected files.
     used with files transtype, the -t flag designates the
type of line endings for the file (mac, unix or win).
     used with files transcode, the -t flag designates the target
encoding of the file.
     otherwise, it is the argument to indicate the target folder in a move,
copy or alias action.


 The -b flag (b stands for 'by') is used only by files list and
allows you to specifiy a sorting option. The option is specified by one of
the letters m, c, s, k, l which correspond respectively to sorting
by Modification date, Creation date, Size, Kind, 
Labels.


It is essential that  the  filtering  regular  expression  be  enclosed  in
brackets if some characters are escaped. The brackets protect  the  escaped
characters from being iterpreted by the Tcl interpreter before the  regular
expressions interpreter. For instance, to designate all files ending with a
dot followed by one single number you want to use the following expression:

     .*\.\d

so you should write on the command line 

    -f {.*\.\d}

If you do not enclose the regular expression in brackets, you  must  escape
the characters twice i-e with a double backslash like this:

    -f .*\\.\\d

or

    -f ".*\\.\\d"

This remark concerns  exclusively  the  regular  expressions  used  on  the
command line: there is no need of brackets when you use the menu items and
dialog windows.

If the -d flag is on (-d 1) the numbering will be done. There is no way  to
set the numbering options from the command line.  The  last  used  settings
will be applied.


6.3.2. Subcommands of the 'files' command

Here is the list of the various subcommands you can append to  the  'files'
command together with the options they accept:

 cmd   subcmds   options                             
 files copy      Required  -t                        
                 Optional  -f -s -l -i -n -all       
 files move      ditto                               
 files rename    Optional  -f -s -l -i -n -c -r -all 
 files transcode Optional -f -s -l -i -n -o -t -all  
 files transtype Optional -f -s -l -i -n -o -t -all  
 files list      Optional  -f -s -l -i -n -b -all    
 files duplicate Optional  -f -s -l -i -n -all       
 files trash     ditto                               
 files lock      ditto                               
 files unlock    ditto                               
 files alias     ditto                               
 files change    Required  -c and/or -t              
                 Optional  -f -s -l -i -n -all       
 files rmalias   Optional  -f -l -all                



6.4. 'infos' command

The 'infos' command is used with a subcommand to  specify  the  item  about
which information is required. Its syntax is:

 infos file path           
 infos folder path         
 infos volume path         
 infos appl path           
 infos process processname 
 infos hardware            


6.5. Commands for browsing

Here are the commands which help you browsing in the files hierarchy, 
or list and edit files:


<pwd >
(print working directory) Prints the current  directory.  The  
name  of  the directory is used in the shell's prompt.

<cd dir>
(change directory) The 'cd' command lets you change the  current  directory.
On OSX, the 'cd' command can resolve tilde and dot symbols at the  beginning
of a path (to designate the user's home  directory  or  the  current  folder
respectively like in any Unix shell). In can be used in different manners:
lt)) 

<cd>
change to Alpha's folder or to the user's home directory depending on 
how the Default Home preference is set (see the Preferences section 
below)

<cd .>
change to directory of second to frontmost window (ie the window which is 
just behind the shell window). If there is no such window or if the window 
does not correspond to a file on disk, the command is equivalent to cd with 
no argument.

<cd ..>
change to parent directory.


To go several levels up, type .. followed by several separators (thus, .. is 
equivalent to ../). E-g:

     cd ..:::
     cd ..///

The following syntax is also accepted (except for [cd /] which changes 
directly to the root folder)

    cd :::         etc.
    cd ///         etc.


<cd blah>
change to subfolder blah of current folder (if blah exists of course)

<cd abs_path>
change to directory corresponding to the absolute path abs_path


<mkdir dir>
(make directory) Create a new subfolder in the current 
folder. If no name is specified, it will be Untitled.

<edit file>
(edit a file) Specify the name of the  file:  if  it  is  in  the  current
directory, the proc will complete the  path.  You  can  use  the  completion
mechanism to enter the name of the file: type the first letters,  then  hit
the Tab key. If the 'edit'  command  is  used  with  no  argument,  you  are
prompted to select a file to edit.

<ls>
(list) Returns a list of all the files and folders contained in the  current
folder. On OSX, this command calls the ls Unix command, so you can  use  all
its flags just like in a Terminal window.

<ld	 >
(list directory) Returns a list of the subfolders contained in  
the current folder.



6.6. Other commands



 empty    to empty the trash                               
 eject    to eject a mounted removable volume              
 restart  to restart the computer                          
 sleep    put the computer in sleeping mode                
 shutdown to shutdown the computer                         
 tutorial to open the tutorial                             
 bindings to display a summary of the MacMenu key bindings 
 version  to get macMenu's version number                  


6.7. Unix commands

On OSX, if a command hasn't been defined as a specific MacShell command  and
fails to be executed as a Tcl command, then MacShell attempts to  invoke  it
as a Unix command. It does this using the exec  Tcl  command:  this  means
that it will work only if it is a non interactive Unix command, i-e if it is
a command which returns its result immediately  without  waiting  for  input
from the user and which does not  have  to  be  terminated  (by  ctrl-D  for
instance). Otherwise Alpha will enter in an infinite loop.
 Typical examples of commands which can be  executed  from  MacShell  are
cal, date, df, ls,  who,  ps  etc.  
But  don't  try  to  execute
commands such as top, stats etc.

6.8. Commands history

As with any Alpha shell, you can move through  commands  history  with  the
'up' and 'down' arrow keys while holding the 'control key' down.
If you option-click in the title bar of the Mac shell, you also have a list
of the last twenty command lines and you can select any of them which  will
be inserted in the shell.

6.9. Extending Mac Shell

You can create your own commands to use in  Mac  Shell.  To  create  a  new
command called mycmd, you must define a proc named macsh::mycmd  and  the
value returned by this proc should be the text you want to be  inserted  in
Mac Shell as a reply when the command is executed. If you  want  no  reply,
just return the empty string "". For instance:

    proc macsh::mycmd {} {
        return "myvalue"
    }


The proc macsh::mycmd can take parameters and arguments depending  on  what
syntax you  want  for  your  command  (subcommands,  additional  arguments,
options etc.). Please see various examples in the files macMenuShell.tcl 
and macMenuInterface.tcl.

You can create as many new commands as  you  wish.  These  commands  can  be
stored in a file like this one. The easiest solution is to locate this  file
in the MacMenu folder and to rebuild the Tcl indices to register your  procs
in Alpha. You must put the following instruction at  the  beginning  of  the
file: 

    namespace eval macsh {}


You can also provide help info about a command by defining an entry in the 
macsh_help() array. Its value must be a list of items corresponding to all 
the subcommands of mycmd.
For instance, if you define

    set macsh_help(mycmd) [list "open [myoptions] [myarguments]" "close"]

the following line will be printed in MacShell when typing help mycmd

    mycmd open [myoptions] [myarguments]
    mycmd close

    
See more examples in the file macMenuShellMore.tcl.

7. MacMenu programming interface
MacMenu provides procedures which can be used in Tcl  scripts  directly  and
make all the MacMenu capacities available programmatically (instead  of  via
the dialogs interface). These procedures have exactly the same syntax as the
commands described in the Mac Shell section: the only difference  is  that
they must be executed in  the  macsh::  namespace.  For  instance,  you  can
invoke, in a Tcl script, the command macsh::files like this:

	macsh::files copy -f {.*\.tex} -t "/Users/bernardo/thesis"


The macsh::files and macsh::infos procs in particular  provide  exactly  the
same functionalities as  the  dialogs  corresponding  to  the  MacMenu  menu
commands. 


8. Completion mechanism

There is a  pathname  completion  mechanism  bound  to  the  tabulation  key
(exactly like in most Unix shells).

Type the first letters of a file's or folder's name and hit the TAB key: the
procedure will try to complete, looking either for the relative or  absolute
path of a file or folder included in the current folder. A complete path  is
supposed to start with a double quote in order to handle spaces in the path.
These double quotes will be added automatically when necessary. If there are
several possible choices, a pick list is displayed.

Note that you can use the symbols tilde and dot at the beginning of  a  path
to designate the user's home directory or the  current  folder  respectively
like in any Unix shell. Mac Shell will do the substitution automatically.

9. Getting info

The Get Info submenu allows  you  to  get  (and  set)  information  about
various kinds of elements:  file,  folder,  volume,  application,  running
process and the computer itself. The results  are  displayed  in  a  dialog
window. 

All these information windows have a button called Get Text to  edit  the
results in a separate text window.

When appropriate, if a specific piece of information has a value which  can
be set or modified, it is edited in an editable field or with a checkbox so
that you can change its value. Use the Set button to validate changes.

The search of information can be slow on... slow machines.  Note  that  the
information about hardware will be sought by the  package  only  the  first
time and recorded since it is not likely to change during a session.

Here is a list of the properties you can find in the info windows (not  all
properties apply to all items of course):

 Owner       Logical size     Modification date     
 Locked      Version info     Logical page size     
 Shared      Creation date    Process partition     
 Comment     Launched from    Largest free block    
 Creator     Physical size    Minimum memory size   
 Version     Remote events    Owner's privileges    
 Capacity    User RAM size    Protected from move   
 ROM size    Stationery pad   System architecture   
 RAM size    Is share point   Low memory area size  
 Ejectable   System version   Allocated memory size 
 Boot disk   Virtual memory   Everyone's privilege  
 CPU family  Bus clock speed  Scripting terminology 
 Free bytes  Hardware vendor  Open Firmware present 
 Scriptable  Software vendor  Processor clock speed 
 Access path Group privileges Suggested memory size 


Hardware info is not available on OSX.

10. Key Bindings

There are a few easy to remember key bindings 'a la emacs'. Press 'ctrl-z',
release, then hit one of the following letters:
._._______________________.
|a|aliases dialog         |
|b|show bindings info     |
|c|copy files dialog      |
|d|duplicate files dialog |
|e|empty the trash        |
|f|delete resource forks  |
|j|eject a disk           |
|k|lock files dialog      |
|l|list files dialog      |
|m|move files dialog      |
|r|rename files dialog    |
|t|send files to the trash|
|u|unlock files dialog    |
|_|_______________________|


You can also use 'ctrl-cmd-y' to open the Mac Shell.
Use the tabulation key to trigger the completion  mechanism  in  Mac  Shell
(see above).


11. Preferences

The Mac Menu Prefs... item in the Packages submenu of the Config
menu allows you to set a few general options:
     the Overwrite If Exists flag concerns already existing files in
the target folder during a move or a copy action. If this flag is set,
you will not be warned about it.  If  not,  you  will  have  an  error
message indicating the name of the already existing file and the  copy
or move will attempt to proceed on the next subfolder: in  this  case
no file will be overwritten. It is safer not to set this flag:  there
is a force overwrite checkbox  in  the  copy  and  move  dialogs  to
temporarily modify this behaviour when necessary.
     the Chunks Size variable is a number:  it  is  the  number  of
files which will be processed simultaneously during a copy or  a  move
action. Due to Apple Events  memory  limitations,  files  have  to  be
processed by chunks. I'm not sure what the optimal value should be.  A
default of 200 has proven absolutely safe with very long access  paths
: with shorter pathnames, it can be increased upto 300 and maybe more.
     the Additional  Types  variable  lets  you  specify  additional
application signatures for the Creator popup in the Change Creator
dialog window.
     the Predef Extensions variable lets you specify the  extensions
which will have a check box of their own in  the  Predef  Exts  dialog
window. 
     the Default Home preference specifies, in Mac Shell, where 
[pwd] should start from and where [cd] without argument should lead to. 
The possible choices are Alpha's folder or User's Home.


12. Version History

     1.0a - 01/01/13 - Created Mac Menu.
     1.0b1 - 01/02/02 - First beta release of Mac Menu.
     1.0b2 - 01/02/02 - Corrected a misplaced key binding.
     1.0b3 - 01/02/26 - Corrected a bug with the 'sharing' button.
     1.0b4 - 01/02/27 - Modified the  make  alias  proc  to  allow  to
specify a target folder for the alias. Added a menu item to make a new
folder in the current directory.
     1.0b5 - 01/02/28 - Removed the New Folder item.
     1.0b6 - 01/03/07 - Cosmetic changes: enlarged various fields  in
the dialog windows which were truncated  with  certain  non-monospaced
system fonts.
     1.0b65 - 01/04/11 - Added a  'Change  Type'  item.  Modified  the
'files change' command in MacShell to accept a -t flag to change files
types. Added an 'edit' command to MacShell.  Added  a  'help  version'
command. Corrected a bug when a volume was selected as a source  or  a
target and a folder with the same name was created  in  the  currfold.
Added new syntax (cd :) in MacShell to 'cd' to parent directory.
     1.0b66 - 01/04/11 - Added ellipses to most menu items.
     1.0b7x - 01/04/04 - Made corrections for compatibility  with  the
new 'file  join'  and  'file  dirname'  behavior.  Includes  the  same
features as the 1.0b6x series. Requires Alpha 7.5.
     1.0b8  -  01/06/19  -  Modifications  for  Alpha8  compatibility.
Modified the behaviour of the AddOptions check box in renaming dialog.
     1.0b81  -  01/06/19  -  Bug  fixed  in  mac::relFilename  (thanks
Frederic). 
     1.0b82 - 01/08/12 - Added a "Transtype  Files"  item  to  convert
line endings (borrowed   from    Johan's    file::convertLineEndings).
Corrected a bug in mac::getItemSize which  did  not  handle  very  big
sizes (more than 0x7fffffff) due to Tcl arithmetic limitations:  big
sizes are now reported in megabytes. Corrected a  bug  when  a  target
folder had to be created and intermediate subfolders did not  exist:
they are now all created.
     1.0b83 - 01/08/23 - Reversed the order of Cancel and OK buttons in 
all dialogs for HIG-compliance. Minor correction in mac::pathLine 
(thanks Johan). 
     1.09 - 01/09/01 - First non beta release (for Alpha 7.4). See 1.1.
     1.1 - 01/09/01 - First non beta release (for Alpha 7.5). Added 
capacity of sorting the list returned by 'list files' according to one 
of five criteria .
("modif date", "kind" etc.) Added a corresponding new -b flag in Mac Shell.
     1.1.1  - 01/09/01 - Added error control in emptyTrash. 
     1.2 - 02/11/08 - Redefined doTranstype for compatibility with Alpha8. 
Added item to delete the resource fork of selected files. 
     2.0 - 03/08/22 - Major overhaul to upgrade to Alphax on OSX. 
     2.1 - 03/11/03 - Bug fixes with the Set button of File Info window. 
     2.2 - 03/11/18 - Eliminated unneeded -r flags in tclAE::send which 
slowed down some commands. Better error checking. Modified the syntax for 
the cd command in MacShell: it is simpler and more robust, it resolves 
tilde paths. New "Default Home" pref on OSX. Correctly 
quotes extensions in filter when they contain metachars. Fixed popup width 
problem introduced by OS Panther. Support for non-interactive Unix 
commands. New MacShell commands. 
     2.3 - 05/06/19 - Eliminated all OS8/9 specific code. Streamlined and 
factored the code for dialogs. Added transcoding facilities.



13. Known problems
     I decided not to implement any erase command because it is potentially
too dangerous: if you want to erase your disks, choose another tool ;-)
     It may happen that, though an action has been performed  
succesfully, its
effect is not displayed immediately by the Finder.
     After long and intensive use, it happens that Alpha seems not to  
execute the Apple Events any more: it is a problem of memory management in 
old versions of Alpha.
Just quit and relaunch the application to refresh it.

Please e-mail any problem or bug you encounter: <bdesgraupes@easyconnect.fr>

Goto the Alpha utilities page:
 <http://webperso.easyconnect.fr/bdesgraupes/alpha.html>


14. License and Disclaimer

(c) Copyright Bernard Desgraupes, 2001-2005
        All rights reserved.
This software is free software distributed under the terms of the  new  BSD
license:
Redistribution and  use  in  source  and  binary  forms,  with  or  without
modification, are permitted provided that the following conditions are met:
     Redistributions of source code must retain the  above  copyright  
notice,
this list of conditions and the following disclaimer.
     Redistributions in binary form must reproduce the above copyright 
notice,
this list of conditions and the following disclaimer in  the  documentation
and/or other materials provided with the distribution.
     Neither the name of Bernard Desgraupes nor the names of its  
contributors
may be used to endorse or  promote  products  derived  from  this  software
without specific prior written permission.

This software is provided by the copyright holders and contributors "as is"
and any express or implied warranties, including, but not limited  to,  the
implied warranties of merchantability and fitness for a particular  purpose
are disclaimed. In no event shall the regents or contributors be liable for
any direct, indirect,  incidental,  special,  exemplary,  or  consequential
damages (including, but not limited to, procurement of substitute goods  or
services; loss of use, data, or profits; or business interruption)  however
caused and  on  any  theory  of  liability,  whether  in  contract,  strict
liability, or tort (including negligence or otherwise) arising in  any  way
out of the use of this software, even if advised of the possibility of such
damage. 
